The MACODBC define is used in the C Include files to indicate the Macintosh environment. Used in SQL.H, SQLEXT.H, ODBCINST.H.
ODBCVERS
Used within the header files to know what version of the ODBC interface is being used. By default it is set to 0x210.
PPCODBC
Used within the sample application and libraries to know if the target is for the 680x0 or the PowerMac. This define is not used within the actual ODBC C Include files.
C Include files
=============
DataTran.h
File contains the prototypes and definitions for the Data Translation library interface.
DBCS.H
File is not currently used on the Macintosh.
ODBCASLM.h
File contains the ASLM specific definitions needed by a 680x0 ODBC application or library.
ODBCINST.H
File contains the prototypes and definitions for the Configuration Manager interface and the Driver Setup library.
ODBCVER.H
File is not currently used on the Macintosh.
SQL.H
File contains the ODBC core level API prototypes and definitions.
SQLEXT.H
File contains the ODBC level 1 and level 2 API prototypes and definitions.
win2mac.h
File contains a set of Macintosh specific definitions. It is used in the SQL.H, and ODBCINST.H include files.
Resource Files
=============
ODBCtypes.r
File contains the ODBC resource definitions for the PowerMac.
CodeFragmentTypes.r
File contains the extended definition of the PowerMac 'cfrg' resource as defined by Apple. The PowerMac ODBC Driver Manager and Configuration Manager are using the "search" fields of the extended 'cfrg' resource to be able to find all ODBC libraries of a given type. The "International Name" field is used as the name that should be presented to the User and is also used to make the association between the driver library and the setup library (i.e. the "International Name" for the driver and setup libraries must match.)
Import Library files
==================
ODBCConfigMgr.cl.o
Configuration Manager Far Model Import library for 680x0/ASLM.
ODBCConfigMgr.cln.o
Configuration Manager Near Model Import library for 680x0/ASLM.
ODBCDriverMgr.cl.o
Driver Manager Far Model Import library for 680x0/ASLM.
ODBCDriverMgr.cln.o
Driver Manager Near Model Import library for 680x0/ASLM.
ODBCConfigMgr.xcoff
Configuration Manager Import Library for PowerMac/CFM.
ODBCDriverMgr.xcoff
Driver Manager Import Library for PowerMac/CFM.
Run Time files
=============
ODBC Setup
This is the ODBC control panel for 680X0/ASLM.
ODBC Driver Manager
ODBC Driver Manager for 680X0/ASLM.
ODBC Configuration Manager
ODBC Configuration Manager of 680X0/ASLM.
ODBC Cursor Library
ODBC Cursor Library for 680X0/ASLM.
ODBC Setup PPC
This is the ODBC control panel for PowerMac/CFM.
ODBC Driver Manager PPC
ODBC Driver Manager for PowerMac/CFM.
ODBC Configuration Manager PPC
ODBC Configuration Manager of PowerMac/CFM.
ODBC Cursor Library PPC
ODBC Cursor Library for PowerMac/CFM.
Building an Application
=====================
Building an ODBC application on the Macintosh is just as easy as it is on
Windows. You include the ODBC header files (SQL.H, SQLEXT.H, etc.), define the MACODBC flag, and link with the appropriate link files as detailed above.
For the 680x0/ASLM environment the application is responsible for initializing and
cleaning up the ASLM Shared Library Manager by calling InitLibraryManager and
CleanupLibraryManager routines. These are the only non-ODBC calls that are
required for a Macintosh application to utilize the ODBC architecture.
ODBC APPLICATION NOTES:
=======================
There is no interoperability between the 68k and the PowerMac architecture.
If you want your application to be able to access 68k libraries on the PowerMac, it is not possible to build a "fat" ODBC application.
Reason: The MacOS must run your application in 68k mode in order to access 68k libraries.
Building an ODBC library
======================
ASLM/680X0 libraries
--------------------
The mechanisms for building and supporting ODBC libraries in the 680X0/ASLM
environment has not changed from those used in ODBC for Macintosh 1.0.
The version of ASLM that is currently incorporated into the ODBC 2.0 SDK is
ASLM version 1.1.2.
To build a 680X0 ODBC library the ASLM developer tools need to be installed into your MPW environment. Verify that this has been done by building one of the ASLM examples.
The ASLM developer tools are not shipped as part of this product. They are available from Apple in various packages including ETO, ...
CFM/PowerMac libraries
----------------------
The native ODBC architecture for the PowerMac is based around the
Code Fragment Manager. The Code Fragment Manager provides similar facilities
to those provided by ASLM, and since it is a native facility of the MacOS
on the PowerMac it is better integrated and better supported by all of the
standard development tools. The one facility that ASLM provided that was not
provided by CFM in it's current implementation was the ability to group and
search for groups of libraries. This facility will be provided in the next
release of the Code Fragment Manager and is currently in beta. The new search
facility will be utilized by CFM and many of it's clients (SOM, Component Manager,
Open Doc and others). We wanted to be compatible with this upcoming
architecture so utilized the extended 'cfrg' resource as defined by Apple
and we implemented our own search routines for now.
The definition for the extended 'cfrg' resource is in ":INCLUDE:CodeFragmentTypes.r".
There are 4 fields of the 'cfrg' resource that are utilized by the ODBC Driver
Manager and/or the Configuration Manager.
Member Name field
-----------------
The "member name" field of the 'cfrg' resource, which is essentially the
library name, is used by the Driver Manager to load a driver.
The member name is saved in the ODBC Preferences file as follows:
[DATA SOURCE SECTION]
driver=<member name>
...
The member name must be unique. In our samples we have used a naming
convention that is much like the naming convention for function sets in
ASLM. Example: vsi:ODBC$SampleDriver. This is just an example and there
is no requirement for driver's to use this naming convention. The only
thing that is required is that the member name be unique within the CFM search
path.
Qualifier 1 Search field.
---------------------
The qualifier 1 search field of the extended 'cfrg' resource is used to define the ODBC library type. There are 4 ODBC library types that are defined in ODBCtypes.r and they are:
These strings and the qualifier 1 field are used by the Configuration Manager to search for all libraries of a given type. A driver writer should utilize the appropriate define in the definition of their 'cfrg' resource when building an ODBC library.
Qualifier 2 Search field.
----------------------
The Qualifier 2 search field replicates the member name field. This field is currently not used by the ODBC architecture, but may be in the future. We wanted to be able to get an exact match from the CFM search facilities for any given ODBC library. Since we currently save the "member name" in the Prefs file, this would allow us to be upwards compatible with the new CFM search facilities when they are available.
International Name field (intlName)
--------------------------------
The International Name field is used by the Configuration Manager in 2 ways:
1) It is the name for a library that is presented to the user.
2) It is used to associate a driver library with a setup library. This means that this field must be an exact match in the driver library and the associated setup library.
ODBC LIBRARY NOTES:
-------------------
If you want your library to be able to run in 68k mode on the PowerMac, it is not possible to build a "fat" ODBC library.
Reason: It is necessary to have different file types and creators for the library (i.e. one for ASLM, one for CFM).
If you want to build a 1.0 driver with the 2.0 SDK, the ODBCVER define needs to be set.
Example:
#define ODBCVER 0x100
Currently all PowerMac ODBC libraries need to be in the Extensions folder.
A new 'odbc' resource id=1 has been added to a driver libraries resource file to support the SQLdriver API call szDriverAttributes parameter. This information in the Windows environment is in the ODBCINST.INI file. On the Macintosh there is no equivalent to this file. See the API Reference and the Sample Driver source for more details.
ODBC Installation
================
The installation of the ODBC components is relatively straight forward. We provide both 680X0/ASLM and PowerMac/CFM based components.
680x0 Environment
-----------------
In the 680X0 environment we install just the 680X0 components. The ASLM libraries (ODBC Driver Manager, ODBC Configuration Manager, and ODBC Cursor Library) are installed in the Extensions folder. The ODBC Setup Control Panel is installed into the Control Panel folder inside the System Folder. The ODBC Preferences file is created on first configuration and is created in the Preferences folder inside the System Folder.
PowerMac Environment
---------------------
In the PowerMac environment we install the PowerMac components as well as the 680x0 components listed above. The CFM libraries ("ODBC Driver Manager PPC", "ODBC Configuration Manager PPC", and "ODBC Cursor Library PPC") are installed in the Extensions folder. The "ODBC Setup PPC" Control Panel is installed into the Control Panel folder inside the System Folder. The "ODBC Preferences PPC" file is created on first configuration and is created in the Preferences folder inside the System Folder.
ASLM Installation
----------------
The ASLM installation is done in both the 680X0 and PowerMac environments. We are licensing the ASLM installation script from Apple. At present I do not know all of the details of what the ASLM installation script is doing. We have modified it just enough to make it run from our disks. What I know is that the "Apple Shared Library Manager" is placed in the Extensions folder and a set of "system hooks" are rez'ed into the System File.
ODBC INSTALLATION NOTES:
------------------------
Due to the installation of ASLM and it's changes to the System file, the Macintosh needs to be restarted after the installation.
The version of ASLM that is currently incorporated into the ODBC 2.0 SDK is
